Saving Files

Note

You are strongly encouraged to make all Navigation Services dialog boxes movable by providing updates via an event-handling function. For more information, see Handling Events.

Users can create a new folder for saving a document by using the New Folder button.

When the user selects a folder, the default button title toggles from Save to Open. When the user selects the editable text field (by clicking or keyboard selection), the default button title reverts to Save.

Save dialog boxes display a focus ring to indicate whether the browser list or the editable text field has keyboard focus (that is, the area that receives all keystrokes.) When no filename is displayed in the editable text field, the Save button is disabled.

IMPORTANT

Always call the function NavCompleteSave after calling the NavPutFile function, even if your application doesn't need automatic translations. Future versions of Navigation Services may provide additional features to your application when it calls the NavCompleteSave function.

Providing File Format Options

The function NavPutFile provides the Format pop-up menu button to allow users to choose how a new document or a copy of a document is to be saved. Figure 17 shows an example of this menu.

Figure 17 Format pop-up menu

Note

If you specify the kNavNoTypePopup constant in the dialogOptionFlags field of the structure NavDialogOptions that you pass in the dialogOptions field of the NavPutFile function, the Format button does not appear in the Save dialog box.

The first item in the Format pop-up menu is defined by the document type specified by your application in the fileType and fileCreator parameters of theNavPutFile function. The name of the menu item is obtained from the Translation Manager. After setting this item, Navigation Services calls the Translation Manager to determine whether to display subsequent menu items describing alternative file types. For more information, see Translating Files on Save.

The last item in the menu is the Stationery Option command. This displays the Stationery Option dialog box, shown in Figure 18 , which lets the user specify whether a new document or a copy of a document should be saved as a document or as stationery.

Figure 18 Stationery Option dialog box

Note

If you clear the kNavAllowStationery constant in the dialogOptionFlags field of the structure NavDialogOptions that you pass in the dialogOptions field of the NavPutFile function, the Stationery Option menu item does not appear.

Translating Files on Save

Your application supplies its default file type and creator for saved files to the function NavPutFile . Navigation Services uses this information to build a pop-up menu of available translation choices obtained from the Translation Manager. If the user selects an output file type that is different from the native type, Navigation Services prepares a translation specification and supplies a handle to it in the fileTranslation field of a structure of type NavReplyRecord . If you choose to provide your own translation, Navigation Services informs you that translation is required by setting the translationNeeded field of the NavReplyRecord structure to true .

IMPORTANT

The function NavTranslateFile is intended to be used only while opening files. Always call the function NavCompleteSave to provide automatic translation and complete a save operation.

When saving a document for the first time, your application should wait until the user closes the document before calling the NavCompleteSave function. This allows your application to save the file in a native format as the user works with the file. When saving a copy of a document, your application should call the NavCompleteSave function immediately after returning from theNavPutFile function.

The NavCompleteSave function provides any necessary translation. If you wish to turn off automatic translation during a save operation, set the value of the translationNeeded field of the NavReplyRecord structure to false before you call the NavCompleteSave function.

Note

You do not need to set the value of the translationNeeded field of the NavReplyRecord structure to false if the user creates a new document that requires translation, but closes it without saving any data.

Once the save is completed, your application must dispose of the NavReplyRecord structure by calling the function NavDisposeReply .

By default, the NavPutFile function saves translations as a copy of the original file. Your application can direct Navigation Services to replace the original with the translation by passing the kNavTranslateInPlace constant, described in Translation Option Constants , in the howToTranslate parameter of the NavCompleteSave function.

A Sample File-Saving Function

Listing 3 illustrates how to save files by using the function NavPutFile . The sample listing also shows how to set options and register your event-handling function. Note that this function uses a DoSafeSave function to ensure that the save is completed without error before an existing file is deleted.

Listing 3 A sample file-saving function



 
OSErr MySaveDocument(WindowPtr theDocument)

{

    OSErr               anErr = noErr;

    NavReplyRecord      reply;

    NavDialogOptions    dialogOptions;

    OSType              fileTypeToSave = 'TEXT';

    OSType              creatorType = 'xAPP';

    NavEventUPP         eventProc = NewNavEventProc(myEventProc);



    anErr = NavGetDefaultDialogOptions(&dialogOptions);

    if (anErr == noErr)

    {

        //  One way to get the name for the file to be saved.

        GetWTitle(theDocument, dialogOptions.savedFileName);

        

        anErr = NavPutFile( nil, &reply, &dialogOptions, eventProc, nil,

                            fileTypeToSave, creatorType );

        if (anErr == noErr && reply.validRecord)

        {

            AEKeyword   theKeyword;

            DescType    actualType;

            Size        actualSize;

            FSSpec      documentFSSpec;

            

            anErr = AEGetNthPtr(&(reply.selection), 1, typeFSS,

                                &theKeyword, &actualType,

                                &documentFSSpec, sizeof(documentFSSpec),

                                &actualSize );

            if (anErr == noErr)

            {

                if (reply.replacing)

                {

                    // Make sure you save a temporary file

                    // so you can check for problems before replacing

                    // an existing file. Once the save is confirmed,

                    // swap the files and delete the original.

                    anErr = DoSafeSave(&documentFSSpec, creatorType,

                                        fileTypeToSave, theDocument);

                }

                else

                {

                    anErr = WriteNewFile(&documentFSSpec, creatorType,

                                         fileTypeToSave, theDocument);

                }

                

                if ( anErr == noErr)

                {

                    // Always call NavCompleteSave() to complete

                    anErr = NavCompleteSave(&reply,

                                            kNavTranslateInPlace);

                }

            }

            (void) NavDisposeReply(&reply);

        }

        DisposeRoutineDescriptor(eventProc);

    }

    return anErr;

}